Customizing value streams

Customize the json file to reflect your typical workflow.

When you create a value stream, default stages and phases are configured and displayed in the Value Stream tab. The structure of the value stream is determined by the json file attached to the value stream. You can customize the json file by using the following methods:

VSM JSON code editor
VSM JSON tree editor
Download the file, modify it, and then reattach it to the value stream by uploading it to HCL™ Accelerate.

A value stream json file consists of the following areas:

The heading identifies the value stream.
The phases defines the value stream's phases and stages. It contains a query that filters the dots appearing in the stage.
The leadTime defines the lead-time metric. In general, lead-time reflects the time from the start of a project until its final disposition.
The cycleTime defines the cycle-time metric. In general, cycle-time reflects the time project elements take to resolve or complete.
The mapping defines status levels for issue tracking systems.
The integration defines integration with external tools. The default stages are empty until you integrate tools into the value stream. You add your tools to a value stream by defining integration objects.
The Metrics provides metric data to the value stream.
The metricsBar section displays metrics data in the value stream Metric bar.
The linkRules defines relationships between integrated tools.

The following code block shows the default value stream json file:

{
  "_id": "velocity-generated-value",
  "pipelineId": "velocity-generated-value",
  "tenantId": "velocity-generated-value",
  "description": null,
  "query": "",
  "phases": [
    {
      "name": "Planning",
      "description": "",
      "stages": [
        {
          "name": "Backlog",
          "query": "",
          "description": "",
          "wipLimit": null,
          "gates": null
        },
        {
          "name": "Queue",
          "query": "",
          "description": "",
          "wipLimit": null,
          "gates": null
        }
      ]
    },
    {
      "name": "Development",
      "description": "",
      "stages": [
        {
          "name": "In Progress",
          "query": "",
          "description": "",
          "wipLimit": 10,
          "gates": null
        },
        {
          "name": "In Review",
          "query": "",
          "description": "",
          "wipLimit": 5,
          "gates": null
        },
        {
          "name": "Merged",
          "query": "",
          "description": "",
          "wipLimit": null,
          "gates": null
        }
      ]
    },
    {
      "name": "Deployment",
      "description": "",
      "stages": [
        {
          "name": "DEV",
          "query": "",
          "description": "",
          "wipLimit": null,
          "gates": null
        },
        {
          "name": "QA",
          "query": "",
          "description": "",
          "wipLimit": null,
          "gates": null
        },
        {
          "name": "PROD",
          "query": "",
          "description": "",
          "wipLimit": null,
          "gates": null
        }
      ]
    }
  ],
  "leadTime": {
    "start": "Backlog",
    "end": "PROD"
  },
  "cycleTime": {
    "start": "In Progress",
    "end": "PROD"
  },
  "mappings": {
    "priority": {
      "Lowest": [
        "Lowest"
      ],
      "Low": [
        "Low"
      ],
      "Medium": [
        "Medium"
      ],
      "High": [
        "High"
      ],
      "Highest": [
        "Highest"
      ]
    }
  },
  "integrations": [],
  "linkRules": [],
  "metrics": [
    {
      "name": "Work Item Type",
      "repeatEvery": "1 minute",
      "repeatAt": null,
      "metricDefinitionId": "WORK_ITEM_TYPE",
      "properties": {
        "query": null,
        "field": "issue.type"
      }
    }
  ],
  "metricsBar": null
}

Heading

The heading properties are common to all value streams.

Table 1. Properties for stages object
Property	Description
_id	Value stream identifier. The value is generated by HCL™ Accelerate.
pipelineId	Identifier of the pipeline associated with the value stream. The value is generated by HCL™ Accelerate.
tenantId	Tenant identifier. The value is generated by HCL™ Accelerate.
description	Value stream description.
query	A query that sets the scope to the entire value stream, not just a stage. If you share a Jira instance, for example, you might define a query that restricts the value stream to a single team's issues.

Phases

The phases JSON array defines the value stream phases and stages. The single phases array for each value stream contains stages objects that define the stages for the containing phase. A phases array can contain any number of stages objects.

The following code fragment shows a Planning phase that contains stages named Backlog Scrum, and Selected for Development.

"phases": [
    {
      "name": "Planning",
      "description": "Planning stage",
      "stages": [
        {
          "name": "Backlog Scrum",
          "query": "issue.status=\"Backlog\"",
          "description": null,
          "wipLimit": null,
          "gates": null
        },
        {
          "name": "Selected For Development",
          "query": "issue.status=\"TO DO\" or issue.status=\"To Do\"",
          "description": null,
          "wipLimit": null,
          "gates": null
        }
      ]
    },

Table 2. Properties for stages object
Property	Description
name	Stage name
query	The DevOps query that defines which dots are displayed in the stage. In general, query parameters reference the tools integrated into the value stream. See the examples later in this topic.
description	Stage description
wipLimit	Represents the 'work in progress' limit. If the number of stage items exceeds the limit, a warning is displayed. To disable warnings, leave the value blank.
gates	Gates determine if objects are valid for a given context. Valid objects are referred to as passing the gate; invalid ones are referred to as failing the gate. Valid objects can appear in value streams.

Lead- and cycle-time metrics

The lead- and cycle-time properties provide useful metrics about value stream performance. The lead-time property reflects the elapsed-time from project start through final disposition. The cycle-time property reflects the time that individual project elements take to complete.

Configure the metrics by assigning a starting stage to the start property, and an ending stage to the end property. For example, if you set start to the Backlog stage, items are tracked when they move from the Backlog stage to the next stage. To carry the example forward, if you set end to the Deployed stage, items are finished when they move into the Deployed stage.

When you configure the metrics, the calculated values are displayed on the Value Stream tab in the Metric bar.

The following code example illustrates typical lead- and cycle-time configurations.


      "leadTime": {
        "start": "Backlog",       
        "end": "Deployed",
      },
       "cycleTime": {
        "start": "In Progress",       
        "end": "Merged",
      },

Mapping

The mappings object defines status values for issue tracking systems. The following code example illustrates the default mappings:

"mappings": {
    "priority": {
      "Lowest": [
        "Lowest"
      ],
      "Low": [
        "Low"
      ],
      "Medium": [
        "Medium"
      ],
      "High": [
        "High"
      ],
      "Highest": [
        "Highest"
      ]
    }
  },

Query examples

A DevOps query determines the dots that are displayed. A query at the value stream level filters, or scopes, the entire value stream. A query at the stage level filters the stage, and a query at the gate level filters the gate. Gates are discussed later in this topic.

In general, query parameters reference the tools integrated into the value stream or applications that belong to the associated pipeline. For a Jira integration you might restrict dots appearing in a stage named "In progress" with the following query:

"query":"issue.status="In Progress"

For a Git integration you can restrict dots appearing in a stage named "Merged" with the following query:

"query":"(pr.status=merged OR pr.status=closed) AND deployment.env!=DEV AND deployment.env!=QA AND deployment.env!=PROD and build.status!=success"

The following code fragment shows a planning phase with several stages and the corresponding queries.

{
      "name": "Development",
      "description": null,
      "stages": [
        {
          "name": "In Progress",
          "query": "issue.status=\"In Progress\" and build.status!=success",
          "description": null,
          "wipLimit": null,
          "gates": null
        },
        {
          "name": "Review",
          "query": "issue.status!=Done and pr.status=open",
          "description": null,
          "wipLimit": null,
          "gates": null
        },
        {
          "name": "Merged",
          "query": "(pr.status=merged OR pr.status=closed) AND deployment.env!=DEV AND deployment.env!=QA AND deployment.env!=PROD and build.status!=success",
          "description": null,
          "wipLimit": null,
          "gates": null
        },
        {
          "name": "Build",
          "query": "build.status=success AND deployment.env!=DEV AND deployment.env!=QA AND deployment.env!=PROD",
          "description": null,
          "wipLimit": null,
          "gates": null
        }
      ]
    },

For more information, see the DevOps query language reference.

Link rules

Link rules define how integrated tools are related to one another. When tools are linked, objects that appear in a value stream provide information and links to the associated tools. You might link an issue tracking system, for example, to a source control tool

When links are established, you can access information about the linked tools from the affected dots in the value stream. In general, you can define linking rules for any integrated tools, and define multiple linking rules in a single value stream.

Metrics

You can provide metric data to your value stream by querying the data integrated into HCL™ Accelerate. The data can originate from plugin integrations, or REST API calls from external clients. DevOps Query Language (DQL) queries can be defined in the value_stream_name-vsm.json file.

You can use the default

Work Item
Type

metric definition as a template for your metrics.

Metric bar

You can provide metrics data to value streams and display the data in charts and graphs attached to the stream. To enable the Metric bar, add metricsBar definitions to the value_stream_name-vsm.json file attached to the value stream.

Integrations array

You provide data from external tools to value streams by defining integration objects. For information about the supported plugins, see Creating value stream integrations.

Troubleshooting

The figure below displays the error message when the value_stream_name-vsm.json file with invalid syntax is uploaded. The error message also displays the .json parse error position in the value_stream_name-vsm.json file. The system will generate similar error messages whenever an invalid value_stream_name-vsm.json file is uploaded.